package com.zenithmind.document.mapper;

import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.zenithmind.document.pojo.domain.DocumentFavorite;
import com.zenithmind.document.pojo.query.DocumentFavoriteQueryDTO;
import com.zenithmind.document.pojo.vo.DocumentFavoriteVO;
import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Param;

import java.util.List;

/**
 * 文档收藏映射器
 * 遵循单一职责原则：专注于文档收藏数据访问
 * 遵循依赖倒置原则：定义抽象的数据访问接口
 * 
 * @author ZenithMind Team
 * @since 2025-01-09
 */
@Mapper
public interface DocumentFavoriteMapper extends BaseMapper<DocumentFavorite> {

    /**
     * 根据文档ID和用户ID查询收藏记录
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @return 收藏记录
     */
    DocumentFavorite selectByDocumentAndUser(@Param("documentId") String documentId, @Param("userId") String userId);

    /**
     * 检查收藏是否存在
     * 
     * @param documentId 文档ID
     * @param userId 用户ID
     * @return 是否存在
     */
    Boolean checkFavoriteExists(@Param("documentId") String documentId, @Param("userId") String userId);

    /**
     * 分页查询收藏详情
     * 
     * @param page 分页参数
     * @param queryDTO 查询条件
     * @return 分页结果
     */
    IPage<DocumentFavoriteVO> selectFavoritePageWithDetails(Page<DocumentFavoriteVO> page, @Param("query") DocumentFavoriteQueryDTO queryDTO);

    /**
     * 查询用户收藏列表
     * 
     * @param userId 用户ID
     * @param folderName 收藏夹名称
     * @param limit 限制数量
     * @return 收藏列表
     */
    List<DocumentFavoriteVO> selectUserFavorites(@Param("userId") String userId, @Param("folderName") String folderName, @Param("limit") Integer limit);

    /**
     * 查询文档收藏用户列表
     * 
     * @param documentId 文档ID
     * @param limit 限制数量
     * @return 用户列表
     */
    List<DocumentFavoriteVO> selectDocumentFavoriteUsers(@Param("documentId") String documentId, @Param("limit") Integer limit);

    /**
     * 查询用户收藏夹列表
     * 
     * @param userId 用户ID
     * @return 收藏夹列表
     */
    List<String> selectUserFavoriteFolders(@Param("userId") String userId);

    /**
     * 检查收藏夹是否存在
     * 
     * @param userId 用户ID
     * @param folderName 收藏夹名称
     * @return 是否存在
     */
    Boolean checkFolderExists(@Param("userId") String userId, @Param("folderName") String folderName);

    /**
     * 创建收藏夹
     * 
     * @param userId 用户ID
     * @param folderName 收藏夹名称
     * @param description 描述
     * @return 影响行数
     */
    Integer createFavoriteFolder(@Param("userId") String userId, @Param("folderName") String folderName, @Param("description") String description);

    /**
     * 删除收藏夹
     * 
     * @param userId 用户ID
     * @param folderName 收藏夹名称
     * @return 影响行数
     */
    Integer deleteFavoriteFolder(@Param("userId") String userId, @Param("folderName") String folderName);

    /**
     * 重命名收藏夹
     * 
     * @param userId 用户ID
     * @param oldFolderName 旧收藏夹名称
     * @param newFolderName 新收藏夹名称
     * @return 影响行数
     */
    Integer renameFavoriteFolder(@Param("userId") String userId, @Param("oldFolderName") String oldFolderName, @Param("newFolderName") String newFolderName);

    /**
     * 将收藏移动到默认收藏夹
     * 
     * @param userId 用户ID
     * @param folderName 收藏夹名称
     * @return 影响行数
     */
    Integer moveFavoritesToDefaultFolder(@Param("userId") String userId, @Param("folderName") String folderName);

    /**
     * 移动收藏到指定收藏夹
     * 
     * @param favoriteIds 收藏ID列表
     * @param targetFolderName 目标收藏夹名称
     * @param userId 用户ID
     * @return 影响行数
     */
    Integer moveFavoritesToFolder(@Param("favoriteIds") List<String> favoriteIds, @Param("targetFolderName") String targetFolderName, @Param("userId") String userId);

    /**
     * 批量取消收藏
     * 
     * @param documentIds 文档ID列表
     * @param userId 用户ID
     * @return 影响行数
     */
    Integer batchCancelFavorites(@Param("documentIds") List<String> documentIds, @Param("userId") String userId);

    /**
     * 搜索用户收藏
     * 
     * @param userId 用户ID
     * @param keyword 关键词
     * @param limit 限制数量
     * @return 收藏列表
     */
    List<DocumentFavoriteVO> searchUserFavorites(@Param("userId") String userId, @Param("keyword") String keyword, @Param("limit") Integer limit);

    /**
     * 查询收藏统计信息
     * 
     * @param userId 用户ID
     * @return 统计信息
     */
    Object selectFavoriteStatistics(@Param("userId") String userId);

    /**
     * 查询热门收藏文档
     * 
     * @param limit 限制数量
     * @return 文档列表
     */
    List<Object> selectHotFavoriteDocuments(@Param("limit") Integer limit);

    /**
     * 查询最近收藏
     * 
     * @param userId 用户ID
     * @param limit 限制数量
     * @return 收藏列表
     */
    List<DocumentFavoriteVO> selectRecentFavorites(@Param("userId") String userId, @Param("limit") Integer limit);

    /**
     * 清理无效收藏
     * 
     * @return 清理数量
     */
    Integer cleanupInvalidFavorites();

    /**
     * 同步收藏统计
     * 
     * @param documentId 文档ID
     * @return 影响行数
     */
    Integer syncFavoriteStatistics(@Param("documentId") String documentId);
}
